home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1991 …esperately Seeking Seven / Desperately Seeking Seven.2mg / Dev.CD.8 / Essentials / Tools / File.Type.Notes / FTN.C7.XXXX < prev    next >
Encoding:
Text File  |  1990-07-27  |  14.8 KB  |  313 lines  |  [04] ASCII Text (0x0000)
  1. Apple II
  2. File Type Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6. File Type:         $C7 (199)
  7. Auxiliary Type:    All
  8.  
  9. Full Name:     Control Panel New Desk Accessory Device (CDev)
  10. Short Name:    Control Panel Document
  11.  
  12. Revised by:    Dave Lyons                                      September 1990
  13. Written by:    Matt Deatherage & Darryl Lovato                 September 1989
  14.  
  15. Files of this type contain CDevs for the Apple IIgs Control Panel New Desk 
  16. Accessory.
  17. Changes since January 1990:  Noted that the MachineCDEV message is not used 
  18. and the RunCDEV message is available only once a second, and made several 
  19. minor corrections.
  20. _____________________________________________________________________________
  21.  
  22. Files of type $C7 contain Control Panel Documents, which are a type of 
  23. miniature "device," which led to their four-letter file type (cdev) on the 
  24. Macintosh.  The same abbreviation is used for modules that work with the Apple 
  25. IIgs Control Panel New Desk Accessory (NDA).
  26.  
  27. The Control Panel NDA is available with Apple IIgs System Software 5.0 and 
  28. later.  The Control Panel acts as a shell around modules which provide the 
  29. user with additional control over aspects of the system.
  30.  
  31.  
  32. Auxiliary Type
  33.  
  34. The auxiliary type of CDevs is defined bit by bit.  Currently, only bit 15 is 
  35. defined--it's the "inactive" bit.  As with desk accessories, FSTs, and setup 
  36. files, the CDev is not loaded or used if this bit is set.  All other bits are 
  37. reserved and must be set to zero.
  38.  
  39.  
  40. How the Control Panel Works
  41.  
  42. The structure behind the Control Panel is conceptually quite easy.  The 
  43. Control Panel NDA receives events from the system which it handles through 
  44. TaskMasterDA.  At certain times, the Control Panel calls CDev routines if the 
  45. CDev indicates this is desirable through the CDev Flags resource.
  46.  
  47. The Control Panel takes care of nearly everything necessary, including 
  48. tracking controls.  CDev windows are basically windows full of extended 
  49. controls, since the only "content" message CDevs receive is that a control was 
  50. hit.
  51.  
  52. Every control in a CDev must be an extended control.  Older, non-extended 
  53. controls are not allowed; all controls must be created with NewControl2.  When 
  54. one of these controls is "hit," the Control Panel calls a routine (if you 
  55. like) with the control handle and ID.  This allows you to take action based 
  56. upon the user's actions.  User interface items beyond extended controls (i.e., 
  57. modal windows) must be handled entirely by the CDev.
  58.  
  59.  
  60. File Format
  61.  
  62. A CDev is defined by three resources (additional resources may be present).  
  63. The data fork of a CDev is reserved and must remain empty.  The three required 
  64. resources are the CDev code resource (type rCDEVCode, $8018), the CDev flags 
  65. resource (type rCDEVFlags, $8019) and the CDev's icon (type rIcon, $8001).
  66.  
  67. The Icon Resource
  68.  
  69. Each CDev's icon is a standard icon resource.  The CDev uses this icon when 
  70. displayed in the Control Panel.  It is also displayed at boot time if the CDev 
  71. has any initialization code (described later).
  72.  
  73. Note:  If the icon is to be displayed during boot time, it must be exactly 28 
  74.        pixels wide.
  75.  
  76. The CDEV Code Resource
  77.  
  78. The CDev's code resource contains the code to do the CDev's work.  A code 
  79. resource has the same format as an OMF load file; the code resource converter, 
  80. which is part of the system, is responsible for loading code resources.  
  81. Eventually, InitalLoad2 loads the code from memory.  This process gives the 
  82. CDev code resource a maximum size of 64K.
  83.  
  84. Once the resource is loaded, the beginning of it is called tool-style with a 
  85. stack diagram as illustrated in Figure 1.
  86.  
  87.     |
  88.     | Result (Long)     Space for result
  89.     |_________________
  90.     |
  91.     | Message (Word)    Indicator of action to take
  92.     |_________________
  93.     |
  94.     | Data1 (Long)      Data passed to CDev
  95.     |_________________
  96.     |
  97.     | Data2 (Long)      Data passed to CDev
  98.     |_________________
  99.     |
  100.     | RTL (3 bytes)     RTL address
  101.     |_________________
  102.  
  103.                       <-- Stack Pointer
  104.  
  105.     Figure 1--Stack Diagram Before Calling CDev
  106.  
  107. The CDev must remove the input parameters from the stack and perform an RTL, 
  108. so the calling routine may then pull the four-byte result parameter off the 
  109. stack.  This function, like nearly all toolbox functions, is a "Pascal" 
  110. function, and may be declared in Pascal as follows:
  111.  
  112.        function MyCDEV(message: Integer; data1, data2: Longint): LongInt;
  113.  
  114. It may be declared in C as follows:
  115.  
  116.        pascal Long MyCDEV(message, data1, data2)
  117.        int message;
  118.        long data1, data2;
  119.  
  120. Data1 and Data2 depend on the value of message.  Message is the parameter that 
  121. tells the CDev code what needs to be done.  Higher-level language CDevs can 
  122. easily be arranged as a giant switch (or case) statement.
  123.  
  124. There are currently ten defined CDev messages.  Where parameters are not 
  125. listed, they are undefined.
  126.  
  127. Message 1:  MachineCDEV
  128.  
  129. The Control Panel always compares the Apple IIgs ROM version against the 
  130. minimum ROM version in the CDev Flags resource.  If the machine's ROM version 
  131. is too low, the CDev does not appear.
  132.  
  133. The MachineCDEV message is currently not used, but future versions of the 
  134. Control Panel may call MachineCDEV, if the wantMachine bit is set in the CDev 
  135. Flags resource, to let the CDev do additional checks to see if it makes sense 
  136. for the CDev to be visible or not.  The parameters are undefined; the CDev 
  137. returns a non-zero result if it should be displayed.
  138.  
  139. Message 2:  BootCDEV
  140.  
  141. If the wantBoot flag is set in the CDev Flags resource, this routine is called 
  142. during the IIgs boot sequence.  The parameters are undefined.
  143.  
  144. BootCDEV is called only during a real boot--it doesn't get control on a switch 
  145. back to GS/OS from ProDOS 8.  The Control Panel draws the icon (from the icon 
  146. resource) on the boot screen.  The icon must be exactly 28 pixels wide if it 
  147. is drawn at boot time.
  148.  
  149. The machine state during this call can be underestimated as "bad."  QuickDraw 
  150. II is not even available; this is called from a setup file belonging to the 
  151. Control Panel.  Be sure to save and restore any system resources you use, 
  152. including the data bank register and the direct page register.  
  153.  
  154. Message 3: Reserved
  155.  
  156. This message is reserved for future use as a shut down message.
  157.  
  158. Message 4:  InitCDEV
  159.  
  160. If the wantInit flag is set in the CDev Flags resource, this routine is called 
  161. with data1 equal to the Control Panel's window pointer.  When InitCDEV is 
  162. called, CreateCDEV (message 7) has already been called.  Controls should have 
  163. been created in CreateCDEV, and this routine is an ideal place to initialize 
  164. the controls before they are displayed.
  165.  
  166. Message 5:  CloseCDEV
  167.  
  168. This routine is called if the wantClose bit is set in the CDev Flags resource.  
  169. If so, CloseCDEV is called when the Control Panel is closing when your CDev is 
  170. the currently selected one or when another CDev is selected.  This is a good 
  171. place to dispose of any memory you allocated or to save settings that need to 
  172. be saved.  The disposal of the CDev's controls is handled by the Control 
  173. Panel.
  174.  
  175. Message 6:  EventsCDEV
  176.  
  177. If the wantEvents bit is set in the CDev Flags resource, the Control Panel 
  178. calls this routine with data1 as a pointer to the event record (this is an 
  179. Event Manager event record, not a TaskMaster-style task record).  The Control 
  180. Panel, like all NDAs, is passed events, which the Control Panel then handles 
  181. by using the TaskMasterDA call.  This routine is called before TaskMasterDA is 
  182. called, so the CDev can change the event record before the Control Panel 
  183. handles it.
  184.  
  185. Message 7:  CreateCDEV
  186.  
  187. This routine is only called if the wantCreate bit is set in the CDev Flags 
  188. resource.  When called, the Control Panel's window pointer is in data1.  The 
  189. CDev must create any controls it has during this call.  The CDev's resource 
  190. fork is open during this call, so Resource Manager calls may be made (and 
  191. controls may be created from resources in the CDev file).  All control 
  192. rectangles are relative to the upper-left corner of the part of the Control 
  193. Panel window a CDev owns while it's selected.  The Control Panel handles 
  194. setting the offsets of the controls to the proper place in the window.  
  195. Initialization of the controls must be done in the InitCDEV call.
  196.  
  197. Message 8:  AboutCDEV
  198.  
  199. If the wantAbout bit is set in the CDev Flags resource, the Control Panel 
  200. calls this routine when the user selects "Help" while your CDev is selected.  
  201. The window pointer to the help window is in data1.  The Control Panel takes 
  202. care of the icon, author, version string and the "OK" button.  The easiest way 
  203. to handle help is simply to create a static text control with the help text in 
  204. it.
  205.  
  206. If the wantAbout bit is not set, your CDev must have an rControlList resource 
  207. with ID $00000002.  When the user selects "Help" while your CDev is selected, 
  208. the Control Panel uses this resource to create your additional About controls.
  209.  
  210. Message 9:  RectCDEV
  211.  
  212. Normally, the Control Panel uses the rectangle in the CDev Flags resource for 
  213. the CDev's display rectangle.  However, if the wantRect bit is set in the CDev 
  214. Flags resource, this routine is called before the CDev is displayed with data1 
  215. containing a pointer to the display rectangle.  The rectangle may be modified 
  216. by this routine.  This gives CDevs the chance to use different sized 
  217. rectangles for different occasions.  For example, on ROM 03, the serial port 
  218. CDevs show fewer parameters when the port is set to AppleTalk (since fewer 
  219. parameters are changeable).  In that instance, the RectCDEV routine changes 
  220. the rectangle to be smaller.
  221.  
  222. Message 10:  HitCDEV
  223.  
  224. If the CDev wants to know when a control has been hit, it can set the wantHit 
  225. bit in the CDev Flags resource.  When called, the handle to the control in 
  226. question is in data1 and that control's ID is in data2.  The CDev may then 
  227. take action based upon the control selection.
  228.  
  229. Message 11:  RunCDEV
  230.  
  231. This routine is called if the wantRun bit in the CDev flags resource is set.  
  232. It enables CDevs to receive a call as often as the Control Panel NDA receives 
  233. run events from SystemTask (currently once per second).
  234.  
  235.  
  236. The CDEV Flags resource
  237.  
  238. The CDEV Flags resource tells the Control Panel NDA which messages the CDev 
  239. code accepts.  It also tells the Control Panel certain things about the 
  240. operating environment required for the CDev.
  241.  
  242.         flags      (+000)  Word        The flags word tells the 
  243.                                        Control Panel which messages 
  244.                                        (defined in the discussion of the 
  245.                                        CDev Code resource) the CDev wants:
  246.                                        Bits 15 - 11:  Reserved, must be 
  247.                                                       zero.
  248.                                        Bit 10:        wantRun
  249.                                                       CDev wants run events.
  250.                                        Bit 9:         wantHit
  251.                                                       CDev wants control hits.
  252.                                        Bit 8:         wantRect
  253.                                                       CDev wants rectangle 
  254.                                                       messages.
  255.                                        Bit 7:         wantAbout
  256.                                                       CDev wants "about" 
  257.                                                       messages.
  258.                                        Bit 6:         wantCreate
  259.                                                       CDev wants create 
  260.                                                       messages.
  261.                                        Bit 5:         wantEvent
  262.                                                       CDev wants event 
  263.                                                       records.
  264.                                        Bit 4:         wantClose
  265.                                                       CDev wants close 
  266.                                                       messages.
  267.                                        Bit 3          wantInit
  268.                                                       CDev wants 
  269.                                                       initialization message.
  270.                                        Bit 2          wantShutDown
  271.                                                       Reserved, must be zero.
  272.                                        Bit 1:         wantBoot
  273.                                                       CDev wants boot 
  274.                                                       messages.
  275.                                        Bit 0:         Reserved, must be zero.
  276.         enabled    (+002)  Byte        If this value is zero, the CDev is 
  277.                                        never activated.
  278.         version    (+003)  Byte        An integer version number assigned by 
  279.                                        the author.
  280.         machine    (+004)  Byte        This byte contains a minimum ROM 
  281.                                        version required for the CDev.  For 
  282.                                        most CDevs this is 1, but some 
  283.                                        (requiring, for example, hardware 
  284.                                        text page two shadowing) want 3 in 
  285.                                        this byte.
  286.         reserved   (+005)  Byte        Reserved, must be zero.
  287.         data rectangle (+006) 4 Words  QuickDraw II rectangle within which 
  288.                                        the CDev is displayed.  The top left 
  289.                                        of this rectangle must be (0,0).
  290.         name       (+014)  16 Bytes    A string (Pascal) giving the name of 
  291.                                        the CDev.  Names longer than 15 bytes 
  292.                                        are not allowed.  Note that this field 
  293.                                        requires 16 bytes regardless of the 
  294.                                        string length.
  295.         author     (+030)  33 Bytes    A string (Pascal) giving the name of 
  296.                                        the CDev's author.  Names longer than 
  297.                                        32 bytes are not allowed.  Note that 
  298.                                        this field requires 33 bytes 
  299.                                        regardless of the string length.
  300.         version    (+063)  9 Bytes     A string (Pascal) giving the version 
  301.                                        of the CDev.  Strings are typically 
  302.                                        of the format "v1.0".  Version 
  303.                                        strings longer than eight bytes are 
  304.                                        not allowed.  Note that this field 
  305.                                        requires nine bytes regardless of 
  306.                                        the string length.
  307.  
  308.  
  309. Further Reference
  310. _____________________________________________________________________________
  311.   o  Apple IIgs Toolbox Reference, Volumes 1-3
  312.  
  313.